Add Spec for IsWindowControlsOverlayEnabled.md #4613
Conversation
tochukwuIbeEkeocha
added
the
API Proposal Review
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
2038eac to
e886ba5
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
2 times, most recently
from
657def7 to
d395730
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
7 times, most recently
from
3866c89 to
bce67e9
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
bce67e9 to
700ec3a
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
700ec3a to
654b176
Compare
|
Is there any ETA on when this update might come to webview2? |
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
654b176 to
5a4eb5f
Compare
Co-authored-by: David Risney <[email protected]>
Co-authored-by: David Risney <[email protected]>
Co-authored-by: Viktoria Zlatinova <[email protected]>
Co-authored-by: Viktoria Zlatinova <[email protected]>
Co-authored-by: Viktoria Zlatinova <[email protected]>
Co-authored-by: David Risney <[email protected]>
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
2f02f47 to
b38a178
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
b38a178 to
a6cc969
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
a6cc969 to
01a2caf
Compare
| # Background | ||
| This API allows you to enable and configure the Webview2 Window Controls Overlay. | ||
| The Overlay is a region on the top right/left of the webview window which contains | ||
| the caption buttons (minimize, maximize, restore, close). Enabing the Overlay allows |
There was a problem hiding this comment.
nit:
| the caption buttons (minimize, maximize, restore, close). Enabing the Overlay allows | |
| the caption buttons (minimize, maximize, restore, close). Enabling the Overlay allows |
| CHECK_FAILURE(coreWebView2->QueryInterface(&coreWebView2_28)); | ||
|
|
||
| wil::com_ptr<ICoreWebView2WindowControlsOverlaySettings> windowControlsOverlaySettings; | ||
| CHECK_FAILURE(coreWebView2_28->get_WindowControlsOverlaySettings(&wco_config)); |
There was a problem hiding this comment.
different variable names, wco_config & windowControlsOverlaySettings
| /// title bar area. Defaults to 48px. There is no minimum height restriction for this API, | ||
| /// so it is up to the developer to make sure that the height of your window controls overlay | ||
| /// is enough that users can see and interact with it. We recommend using GetSystemMetrics(SM_CYCAPTION) | ||
| // as you minimum height. |
There was a problem hiding this comment.
| // as you minimum height. | |
| // as your minimum height. |
| /// The Overlay buttons will sit on top of the HTML content, and will prevent mouse interactions | ||
| /// with any elements directly below it, so you should avoid placing content there. | ||
| /// To that end, there are four [CSS environment vairables](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API#css_environment_variables) | ||
| /// titlebar-area-x, titlebar-area-y, titlebar-area-width defined to help you |
| /// To that end, there are four [CSS environment vairables](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API#css_environment_variables) | ||
| /// titlebar-area-x, titlebar-area-y, titlebar-area-width defined to help you | ||
| /// get the dimensions of the available titlebar area to the left of the overlay. | ||
| /// Similarly the navigator object wil contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay) |
There was a problem hiding this comment.
| /// Similarly the navigator object wil contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay) | |
| /// Similarly the navigator object will contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay) |
|
|
||
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will |
There was a problem hiding this comment.
| ///will automatically calculate a foreground and hover color that will | |
| /// will automatically calculate a foreground and hover color that will |
|
|
||
| CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebivew2.WindowControlsOverlaySettings; | ||
| config.IsEnabled = true; | ||
| config.color = Color.FromARGB(0, 0, 255); |
There was a problem hiding this comment.
Does the order of setting these properties matter? If I set enabled=true before setting .color might there be a frame rendered of the overlay with the default color?
| [propget] HRESULT TitleBarBackgroundColor([out, retval] COREWEBVIEW2_COLOR* value); | ||
|
|
||
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 |
There was a problem hiding this comment.
This is the overlay, so why is it called TitleBarBackgroundColor? https://wicg.github.io/window-controls-overlay/#concepts suggests this color will apply to the controls overlay, not the "title bar area". Based on the API comments for IsEnabled "You are responsible for creating a title bar for your app" I understand us to have removed the title bar from being system-controlled UI.
Property name can be just "BackgroundColor" if it refers to the background color of the WindowControlsOverlay, since it's in the context of being a CoreWebView2WindowControlsOverlaySettings property.
| /// | ||
| /// When using this you should configure your app window to not display its default | ||
| /// window control buttons. You are responsible for creating a title bar for your app | ||
| /// by using the available space to the left of the controls overlay. In doing so, |
There was a problem hiding this comment.
Is this right or left conditional on the reading direction of the UI root?
|
|
||
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will |
There was a problem hiding this comment.
Is foreground color necessarily black or white? We might be leaving this undocumented to reserve the right to choose colors based on the hosting app?
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will | ||
| /// provide you the best contrast while maintaining accessibility. |
There was a problem hiding this comment.
"best" is subjective. I suggest documenting just which guarantees WebView2 is making regarding color and contrast. I suspect this is something like e.g. "WebView2 will use a foreground color that maintains at least 3:1 contrast radio with your chosen color."
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will | ||
| /// provide you the best contrast while maintaining accessibility. | ||
| /// Defaults to #f3f3f3. This API supports transparency. |
There was a problem hiding this comment.
What does it mean to "maintain accessibility" if the background color is transparent. I expect at that point we can't make any guarantee about the foreground color relative to the webview content. Is it in scope to consider that?
What
These new APIs introduce support for a Webview2 Window Controls Overlay. The Window Controls Overlay will allow developers to build apps in webview2 with 100% of the UI controlled by the browser process. Devs will be able to create their apps as borderless & caption-less windows, and have the Webview draw its own window control buttons (minimize,maximize, close, restore).